Input file formats↑ Return to top

This is a description of the input formats known by V_Sim. Each format has examples of its own in the $prefix/share/doc/v_sim/examples directory after installation or in the ~/examples directory in the sources package.

Native binary format (*.d3)↑ Return to top

.d3 format has been defined by Frédéric LANÇON (frederic DOT lancon AT cea.fr).

This is a binary format tuned for Fortran output. One example can be downloaded from this site and others are available in the examples directory of the V_Sim source distribution. Read this file for a full description (still in French) of the format. In short, this is a Fortran file with the following records:

• A title [CHARACTER*128] ;
• The total number of atoms and the number of different types [INTEGER*4, INTEGER*4] ;
• The number of atoms for each type and the name of elements for each type also [INTEGER*4 (NTYPES), CHARACTER*8 (NTYPES)] ;
• The box [REAL*8 (6)], see the ASCII format ;
• All x coordinates [REAL*8 (NAT)] ;
• All y coordinates [REAL*8 (NAT)] ;
• All z coordinates [REAL*8 (NAT)].

There is also a variation of this file format that can be used to store as many set of positions as desired. This is similar to the common XYZ allows to do. The description of this '-posi.d3' format can be found here.

Native plain text format (*.ascii)↑ Return to top

All the data are in plain text. Here is a commented example.

• 1st line is arbitrary
• 2nd line must contain dxx dyx dyy values
• 3rd line must contain dzx dzy dzz values
• other lines may contain:
  • keywords, with the syntax [#!]keyword: followed by a list of keywords, separated by commas or blank spaces (from version 3.5).
  • comments beginning with '#' or '!'
  • x y z name [label] for atomic position and optional labels

dxx dyx dyy dzx dzy dzz values define the box that contains the atoms. It is not necessary orthonormal. See the figure on the right to know how these values are interpreted. Since a box is explicitly given in the format, these files are considered as periodic files by V_Sim and some action are thus available, such as the translation in the box (see the user guide). When the keyword angdeg is used, the six values contains the three lengths of basis vectors in dxx dyx and dyy, and the three angles (bc, ac, ab) in dzx dzy and dzz.

After the three first mandatory lines, all subsequent lines can be comment lines (ignored), i.e. empty, containing only blanks, or beginning with ! or with #. A non comment line must contain 'x y z name', giving the 3 coordinates and the name of the atom. The coordinates of the atoms are given in the orthonormal basis not in the box basis. In case the keyword reduced has been specified, the three coordinates x, y and z are given in the box basis.

Please note that the name must contain at most 8 characters (non blank).

Please also note that real values are in free format. However, (Fortran) format like 1.03D+05 is NOT SUPPORTED and must be written 1.03E+05 (or 1.03e+05).

The keywords have been introduced in version 3.5. They can be positionned anywhere after the first three lines. The following table summurises all available keywords:

From version 3.6, the keywords have been completed by meta data. Meta data are just additional information that does not affect directly the crystal definition given by the file. They can be positionned anywhere after the first three lines. The following table summurises all available meta data:

#metaData: qpt=[0.167;0.167;0.0000;-0.000039 \ 
#; 0.542135; 0.542135; 0.626392; 0.020661; 0.020661; 0.028839 \ 
#; 0.542506; 0.542506; 0.626965; -0.00492; -0.00492; -0.01065 \ 
#; 0.544070; 0.544077; 0.623979; 0.008137; 0.007647; 0.009051 \ 
#; 0.544077; 0.544070; 0.623979; 0.007647; 0.008137; 0.009051 \ 
#; 0.545224; 0.546040; 0.629614; -0.05386; -0.04485; -0.05695 \ 
#; 0.547737; 0.547868; 0.632119; 0.012470; 0.003422; 0.009170 \ 
# ]

Here is a short example for silicon:

# V_Sim ASCII format for primitive cell of silicon
  3.83959 3.83959 3.83959
  60      60      60
#keyword: angdeg, reduced
#metaData: totalEnergy=16.42378915Ht
	0.00    0.00    0.00  Si
	0.25	0.25	0.25  Si

Widely used text format (*.xyz)↑ Return to top

Common conventions

This is a common format for sharing atomic position. V_Sim supports it only for atoms positions. The format is quite free, each blank line or line beginning with a '#' is not read. Otherwise, V_Sim try to match 'string_name float_x float_y float_z' and considers that there is an atom whose name is string_name at the position (float_x, float_y, float_z). The two first lines are mandatory, the first with the number of elements and the second kept as a commentary.

One can use this format to store several configurations in one file. To do it, just append several valid blocks of two lines followed by element names and positions.

There is no box consideration thus some functionalities are disabled when this format is used. Even if internaly, V_Sim create a box around all atoms to represent them.

Special additions

In the BigDFT project, some extensions as been introduced in this format to support box, boundary conditions... V_Sim is fully compatible with these extensions:

• Define length units: add 'angstroem', 'bohr', 'reduced' or 'atomic' after the number of atoms on first line. 'atomic' is a equivalent keyword for 'bohr'.
• Define the boundary conditions with a starting keyword on the second line: 'freeBC', 'surface' or 'periodic' for respectively free boundary conditions, surface Y oriented conditions and 3D periodic conditions.
• For periodic conditions, a box has to be defined by giving 3 floating point values after the keyword on the second line. The box is automatically orthorombic.

Here is a short example of a slab made by water molecules:

3 angstroem
surface 3.0 0.0 3.0
O 1.5     0.0    1.5    
H  .7285 0.620919 1.5 
H  2.2715  0.620919 1.5 

Format for spin (*.spin)↑ Return to top

Here is an example (here is the associated d3 file).

This format describes spin data for a given number of atoms. Keep in mind a spin file is loaded along with a position file such as the ones described above. If the position file you're using contains 'n' atoms, then your spin file should contain at least 'n+1' lines.

1st line of a spin file is arbitrary. Then each of the following lines must match the pattern [(line_number - 1), (float_module), (float_theta), (float_phi)] where theta and phi are the classical physics spherical coordinates that set the spin orientation. Set module to 0. if you want V_Sim not to render the element. Lines after the 'n+1'-th are free for you to use.

Other formats (through plugins)↑ Return to top

All previous formats are natively supported by V_Sim. It is possible to extent this list using plug-ins. V_Sim is shipped with several official plug-ins that make the following formats available:

• ETSF: a plug-in to read the ETSF file format as described in the ETSF specifications. This plug-in supports the crystallographic description and the density storage.
• obloader: a plug-in based on OpenBabel. It wraps the OpenBabel parsers and gives access to a long list of crystallographic files.
• xsf: a plug-in to read the XCrysDen files. It supports the crystallographic description and the forces also. The support for densities has been partially implemented in version 3.6.
• cube: a plug-in to read the CUBE files as described by Gaussian. Both the crystallographic and the density descriptions are supported.
• abinit: a plug-in that wraps the ABINIT input file parser. It supports the multi datasets and the crystallographic information.

Configuration file format↑ Return to top

There are two configuration files. The first v_sim.res is called resources file. It is used to store all informations that have an influence on the rendering (e.g. the color, the atomic radius, the prefered pairs rendering method..). The second, v_sim.par, is called parameters file. It stores everything that is used to configure V_Sim (e.g. refresh time, gtk options...).

When V_Sim starts, these two file are looked up in the current working directory, if not found, ~/$XDG_CONFIG_HOME/v_sim is searched and finally, the installation directory. Only a resources file can be re-loaded after startup.

Resources file (v_sim.res)↑ Return to top

Here is an example. Lines beginning with a # are not parsed. Each resource is identified by a markup (a string without space, finished by ':') and followed by one or several lines of values. The valid markup are listed at the begining of the given example, and an extensive list is given here:

Parameters file (v_sim.par)↑ Return to top

Here is an example. t is read once at startup. Line beginning with a # are not parsed. Each parameter is identified by a markup (a string without space, finished by ':') and directly followed by its value. The valid markup are listed at the begining of the given example. A flag can be appended to the identifier to tell V_Sim if the line should be ignored depending on the way V_Sim is used (gtk flags are not read when V_Sim run as a command line tool for example). The extensive list is available below:

RC file (v_sim.rc)↑ Return to top

Here is an example. This file is used by GTK to skin the application. It follows the classical Gtkrc syntax (see gtk online documentation for further explanations).

Isosurfaces data file format↑ Return to top

Isosurfaces files (*.surf)↑ Return to top

Here is an example (here is the associated ascii file).

These files describe isosurfaces data. You can load them through the 'isosurfaces' panel. They are in utf-8 format. They have the following format:

• 1st line is arbitrary
• 2nd line must contain 3 real values : dxx dyx dyy
• 3rd line must contain 3 real values : dzx dzy dzz
• 4th line must contain 3 positive integers:
  number of surfaces, total num_polys, total num_points
• then, for each of these surfaces :
  • As musch commentary lines as required (i.e. lines beginning with a # character).
  • If one line is a commentary and begins with # potentialValue followed by a value, then this value is used as the value which the surface corresponds to and will be set in the graphical interface.
  • Next line must contain the name of the surface (may be left empty).
  • Next line must contain 2 positive integer values : num_polys and num_points
  • Each of the following num_polys lines must contain :
    n i_1 i_2 i_3 ... i_n where n is the number of vertices in the poly (n >= 3) and i_1 i_2 i_3 ... i_n are the numbering of these vertices [vertices numbered from 1 to num_points]
  • Each of the following num_points lines must contain 6 real values for the successive (1 to num_points) points:
    x y z nx ny nz
    where x y z are the coordinates of the point
    and nx ny nz are the coordinates of the unit normal at the point

Potential files (*.pot)↑ Return to top

It is a text file with the following format :

• 1st line : arbitrary
• 2nd line : 3 positive integers na nb nc
• 3rd line : 3 real numbers dxx dyx dyy
• 4th line : 3 real numbers dzx dzy dzz
dxx, dyy and dzz should be positive. One assumes that the potential is given as na*nb*nc values at the nodes of a triclinic grid built on a box defined by dxx dyx dyy dzx dzy dzz.
  i.e. the grid is built from :
  • na points along axis a (dxx, 0, 0) for equal na intervals
  • nb points along axis b (dyx, dyy, 0) for equal nb intervals
  • nc points along axis c (dzx, dzy, dzz) for equal nc intervals
• 5th line: one of the chain xyz OR zyx which says respectively if a values vary fastest, then b values, then c values OR c values vary fastest, then b values , then a values. From version 3.4, on the same line, an optional second string can be given. Its value is 'periodic'. When present, the last value in a direction is not at reduce coordinate 1. but at (1. - 1 / n) and value at coordinate 1. is taken equals to the value at coordinates 0.
• next lines (in free format) : the na*nb*nc values

Instruction files (*.instruc)↑ Return to top

These are utf-8 text files with the following format :

• 1st line : full pathname of the potential file to read (see further)
• 2nd line: full pathname of the surface file to build (see further)
• 3rd line: an integer giving the nbr n of isosurfaces to build
• On each of the n following lines
  surf_value, surf_name where surf_value is a real number for the isovalue and surf_name is the name given for the corresponding isosurface to build

XML data file format↑ Return to top

It is possible to save most of the selected data during an interactive session of V_Sim into a file. These data includes: planes, highlighted nodes or iso-surface definitions.

All these data have an XML format definition that can be concatenated into a single XML file:

Planes data file format↑ Return to top

It is possible to write a file describing planes (or tell V_Sim to export current planes). This file is an XML file. The structure is quite simple and correspond to the following DTD:

Surfaces data file format↑ Return to top

It is possible to write a file describing created surfaces (or tell V_Sim to export current surfaces). This file is an XML file. The structure is quite simple and correspond to the following DTD:

Pick data file format↑ Return to top

It is possible to write a file with the picked nodes (or tell V_Sim to export current picked ones). This file is an XML file. The structure is quite simple and correspond to the following DTD:

Paths data file format↑ Return to top

It is possible to write a file with the node displacements saved as a path between several data files. This file is an XML file. The structure is quite simple and correspond to the following DTD: